/*******************************************************************************
 * Copyright (c) 2010 Mikhail Garber.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the GNU Lesser Public License (LGPL)
 * which accompanies this distribution
 * 
 * Contributors:
 *     Mikhail Garber - initial API and implementation
 ******************************************************************************/
package plumber.coordinator;

import java.util.Date;
import java.util.List;

import plumber.common.WorkItem.Status;

/**
 * this interface defines how a WorkManager (fleet of workers) communicates with a Coordinator
 * @author mgarber
 *
 */
public interface CoordinatorServer {

	/**
	 * get candidate work items to be executed (that are in AVAILABLE state)
	 * @param namespace use
	 * @param upto this many items
	 * @return list of string representations of WorkItems
	 */
	public List<String> getCandidates(String namespace, int upto);
	
	/**
	 * attempt to claim a candidate WOrkItem. Successful claim represents commitment of this WorkManager
	 * to execute this work item
	 * @param id of the item
	 * @return true or false (ok or not to claim it)
	 */
	public boolean claimCandidate(String id);
	
	/**
	 * create next WorkItem to advance execution of a Flow to a next Step
	 * @param context - FlowContext as String
	 * @param oldItemId - id of current WorkItem
	 * @param nextStepId - id of next Step to execute
	 * @param oldStatus - status of current WorkItem
	 * @param scheduled - when next Step needs to be executed
	 */
	public void advanceWork(String context, String oldItemId, String nextStepId, Status oldStatus, Date scheduled);
}
